3. Merchant Integration Flow: Card Tokenisation and Tokenised Payments

3.1.9 Tokenisation: Step 6 – Asynchronous WebHooks Response from Payment Gateway for the Payment

3.1.9.1 Webhooks

WebHooks allow the merchant to configure one or more merchant specific end–points to be responded to by the Payment Broker and will be consumed by a merchant's custom service of their own design.
The WebHooks are processed by posting a Base64 encoded JSON payload to the configured URL(s) as defined in the WebHooks.WebHook.Template field.
The WebHooks URLs are processed after a successful or failed payment on the Payment Gateway.
The template will contain one or more of the fields from payment gateway which are parametrised by enclosing them in hashes (#) .
The parameterised fields are substituted by Payment Gateway with the actual values on post-back, and would allow your end-point to be notified of those values, so that you could update your order status with the outcome of the payment.
See 4.4 Appendix D: Payment Gateway Response Codes

3.1.9.2 Webhook Payment Response Template

Figure 10. Tokenisation: Step 6 – Tokenisation Payment Asynchronous Response Possible Fields

3.1.9.3 Webhook Payment Response Template Field Definition

The following list of possible fields can be defined in the WebHook template:

Table 11. Tokenisation: Step 6 – WebHook Transaction Response Template Field Definition
# Field
(Case–Sensitive)		 Required
Mandatory
Optional		 Type Length Description
1. Type ^ M String Must be set to recurringpaymentcallback
2. ControlKey M String Encrypted value used to check that the values posted back correspond to a valid Payment Gateway post–back for the TransactionStatusCallbackURL.
It is constructed using a Hash of the Stamp/Session/Identifier encrypted with the merchant's encryption key).
See 4.3. Appendix C: Control Key for details on how this value is generated.
3. Identifier M String Value that uniquely identifies an order submitted for processing.
4. MerchantReference M String 20 This is the unique value that is used by the Merchant to identify the transaction on his system.
5. Amount M Decimal The purchase amount of the transaction.
6. RequestIdentifier M String 50 Included by the merchant to uniquely identify the transaction on his system..
7. TransactionReference M String 21 The unique identifier of the transaction on the payment gateway.
Will always contain a value in the case of a successful transaction.
8. ErrorDescription M String 250 The description of the error that has occurred.
Can be empty.
Will only contain value if there was an error.
See 4.4 Appendix D: Payment Gateway Response Codes
9. ErrorCode M String 3 Error code returned.
"00" – the transaction was accepted and will be processed.
Non–zero value otherwise.
See 4.4 Appendix D: Payment Gateway Response Codes
10. BankResponseCode M String See 4.5. Appendix E: Bank Response Codes.
11. BankResponseDescription M String 3 See 4.5. Appendix E: Bank Response Codes.
12. TransactionStatus M String Indicates the current status of transaction.
Valid values:
  • Success (check for this instead of ErrorCode="00")
  • Failure/Error
    		•
    13. Currency M String 3 Country currency.
    Supply the 3 character ISO currency code.
    Defaults to "ZAR".
    14. SupplierID M String This is the VPG assigned merchant identifier.
    The SupplierID field value will be submitted as SupplierAlias which are synonymous.
    e.g. "VC Upfront Payments" Will be provided by VFS after merchant on-boarding.
    15. Stamp M String 38 Unique identifier passed by the merchant representing the instance of the transaction request.
    If no stamp is passed by the merchant no stamp is returned.
    16. CustomerIdentifier M String The unique id sent to the payment gateway if sent by the merchant.
    17. MerchantIdentifier M String 38 The GUID id of the merchant in the payment gateway.
    18. MaskedCardNumber M String The PAN (Card Number) of the customer's card used to make the payment masked with asterisk's to show only the last four–digits.
    19. RetrievalReferenceNumber M String The reference that is used to track the transaction with the bank.

    Continue

    Return